opencode-docs.md Rules Set custom instructions for opencode. You can provide custom instructions to opencode by creating an AGENTS.md file. This is similar to Cursor’s rules. It contains instructions that will be included in the LLM’s context to customize its behavior for your specific project. Initialize To create a new AGENTS.md file, you can run the /init command in opencode. Tip You should commit your project’s AGENTS.md file to Git. /init scans the important files in your repo, may ask a couple of targeted questions when the codebase cannot answer them, and then creates or updates AGENTS.md with concise project-specific guidance. It focuses on the things future agent sessions are most likely to need: build, lint, and test commands command order and focused verification steps when they matter architecture and repo structure that are not obvious from filenames alone project-specific conventions, setup quirks, and operational gotchas references to existing instruction sources like Cursor or Copilot rules If you already have an AGENTS.md, /init will improve it in place instead of blindly replacing it. Example You can also just create this file manually. Here’s an example of some things you can put into an AGENTS.md file. AGENTS.md # SST v3 Monorepo Project This is an SST v3 monorepo with TypeScript. The project uses bun workspaces for package management. ## Project Structure - `packages/` - Contains all workspace packages (functions, core, web, etc.) - `infra/` - Infrastructure definitions split by service (storage.ts, api.ts, web.ts) - `sst.config.ts` - Main SST configuration with dynamic imports ## Code Standards - Use TypeScript with strict mode enabled - Shared code goes in `packages/core/` with proper exports configuration - Functions go in `packages/functions/` - Infrastructure should be split into logical files in `infra/` ## Monorepo Conventions - Import shared modules using workspace names: `@my-app/core/example` We are adding project-specific instructions here and this will be shared across your team. Types opencode also supports reading the AGENTS.md file from multiple locations. And this serves different purposes. Project Place an AGENTS.md in your project root for project-specific rules. These only apply when you are working in this directory or its sub-directories. Global You can also have global rules in a ~/.config/opencode/AGENTS.md file. This gets applied across all opencode sessions. Since this isn’t committed to Git or shared with your team, we recommend using this to specify any personal rules that the LLM should follow. Claude Code Compatibility For users migrating from Claude Code, OpenCode supports Claude Code’s file conventions as fallbacks: Project rules: CLAUDE.md in your project directory (used if no AGENTS.md exists) Global rules: ~/.claude/CLAUDE.md (used if no ~/.config/opencode/AGENTS.md exists) Skills: ~/.claude/skills/ — see Agent Skills for details To disable Claude Code compatibility, set one of these environment variables: Terminal window export OPENCODE_DISABLE_CLAUDE_CODE=1 # Disable all .claude support export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1 # Disable only ~/.claude/CLAUDE.md export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 # Disable only .claude/skills Precedence When opencode starts, it looks for rule files in this order: Local files by traversing up from the current directory (AGENTS.md, CLAUDE.md) Global file at ~/.config/opencode/AGENTS.md Claude Code file at ~/.claude/CLAUDE.md (unless disabled) The first matching file wins in each category. For example, if you have both AGENTS.md and CLAUDE.md, only AGENTS.md is used. Similarly, ~/.config/opencode/AGENTS.md takes precedence over ~/.claude/CLAUDE.md. Custom Instructions You can specify custom instruction files in your opencode.json or the global ~/.config/opencode/opencode.json. This allows you and your team to reuse existing rules rather than having to duplicate them to AGENTS.md. Example: opencode.json { "$schema": "https://opencode.ai/config.json", "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"] } You can also use remote URLs to load instructions from the web. opencode.json { "$schema": "https://opencode.ai/config.json", "instructions": ["https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"] } Remote instructions are fetched with a 5 second timeout. All instruction files are combined with your AGENTS.md files. Referencing External Files While opencode doesn’t automatically parse file references in AGENTS.md, you can achieve similar functionality in two ways: Using opencode.json The recommended approach is to use the instructions field in opencode.json: opencode.json { "$schema": "https://opencode.ai/config.json", "instructions": ["docs/development-standards.md", "test/testing-guidelines.md", "packages/*/AGENTS.md"] } Manual Instructions in AGENTS.md You can teach opencode to read external files by providing explicit instructions in your AGENTS.md. Here’s a practical example: AGENTS.md # TypeScript Project Rules ## External File Loading CRITICAL: When you encounter a file reference (e.g., @rules/general.md), use your Read tool to load it on a need-to-know basis. They're relevant to the SPECIFIC task at hand. Instructions: - Do NOT preemptively load all references - use lazy loading based on actual need - When loaded, treat content as mandatory instructions that override defaults - Follow references recursively when needed ## Development Guidelines For TypeScript code style and best practices: @docs/typescript-guidelines.md For React component architecture and hooks patterns: @docs/react-patterns.md For REST API design and error handling: @docs/api-standards.md For testing strategies and coverage requirements: @test/testing-guidelines.md ## General Guidelines Read the following file immediately as it's relevant to all workflows: @rules/general-guidelines.md. This approach allows you to: Create modular, reusable rule files Share rules across projects via symlinks or git submodules Keep AGENTS.md concise while referencing detailed guidelines Ensure opencode loads files only when needed for the specific task Tip For monorepos or projects with shared standards, using opencode.json with glob patterns (like packages/*/AGENTS.md) is more maintainable than manual instructions. ================================================================ Permession ----------- { "$schema": "https://opencode.ai/config.json", "permission": "allow" } --------- { "$schema": "https://opencode.ai/config.json", "permission": { "*": "ask", "bash": "allow", "edit": "deny" } } ---- { "$schema": "https://opencode.ai/config.json", "permission": { "bash": { "*": "ask", "git *": "allow", "npm *": "allow", "rm *": "deny", "grep *": "allow" }, "edit": { "*": "deny", "packages/web/src/content/docs/*.mdx": "allow" } } } ------ Wildcards Permission patterns use simple wildcard matching: * matches zero or more of any character ? matches exactly one character All other characters match literally Home Directory Expansion You can use ~ or $HOME at the start of a pattern to reference your home directory. This is particularly useful for external_directory rules. ~/projects/* -> /Users/username/projects/* $HOME/projects/* -> /Users/username/projects/* ~ -> /Users/username External Directories Use external_directory to allow tool calls that touch paths outside the working directory where OpenCode was started. This applies to any tool that takes a path as input (for example read, edit, glob, grep, and many bash commands). Home expansion (like ~/...) only affects how a pattern is written. It does not make an external path part of the current workspace, so paths outside the working directory must still be allowed via external_directory. For example, this allows access to everything under ~/projects/personal/ { "$schema": "https://opencode.ai/config.json", "permission": { "external_directory": { "~/projects/personal/**": "allow" } } } ============================================== Agents ====== Agents Configure and use specialized agents. Agents are specialized AI assistants that can be configured for specific tasks and workflows. They allow you to create focused tools with custom prompts, models, and tool access. Tip Use the plan agent to analyze code and review suggestions without making any code changes. You can switch between agents during a session or invoke them with the @ mention. Types There are two types of agents in OpenCode; primary agents and subagents. Primary agents Primary agents are the main assistants you interact with directly. You can cycle through them using the Tab key, or your configured switch_agent keybind. These agents handle your main conversation. Tool access is configured via permissions — for example, Build has all tools enabled while Plan is restricted. Tip You can use the Tab key to switch between primary agents during a session. OpenCode comes with two built-in primary agents, Build and Plan. We’ll look at these below. Subagents Subagents are specialized assistants that primary agents can invoke for specific tasks. You can also manually invoke them by @ mentioning them in your messages. OpenCode comes with two built-in subagents, General and Explore. We’ll look at this below. Built-in OpenCode comes with two built-in primary agents and two built-in subagents. Use build Mode: primary Build is the default primary agent with all tools enabled. This is the standard agent for development work where you need full access to file operations and system commands. Use plan Mode: primary A restricted agent designed for planning and analysis. We use a permission system to give you more control and prevent unintended changes. By default, all of the following are set to ask: file edits: All writes, patches, and edits bash: All bash commands This agent is useful when you want the LLM to analyze code, suggest changes, or create plans without making any actual modifications to your codebase. Use general Mode: subagent A general-purpose agent for researching complex questions and executing multi-step tasks. Has full tool access (except todo), so it can make file changes when needed. Use this to run multiple units of work in parallel. Use explore Mode: subagent A fast, read-only agent for exploring codebases. Cannot modify files. Use this when you need to quickly find files by patterns, search code for keywords, or answer questions about the codebase. Use compaction Mode: primary Hidden system agent that compacts long context into a smaller summary. It runs automatically when needed and is not selectable in the UI. Use title Mode: primary Hidden system agent that generates short session titles. It runs automatically and is not selectable in the UI. Use summary Mode: primary Hidden system agent that creates session summaries. It runs automatically and is not selectable in the UI. Usage For primary agents, use the Tab key to cycle through them during a session. You can also use your configured switch_agent keybind. Subagents can be invoked: Automatically by primary agents for specialized tasks based on their descriptions. Manually by @ mentioning a subagent in your message. For example. @general help me search for this function Navigation between sessions: When subagents create child sessions, use session_child_first (default: +Down) to enter the first child session from the parent. Once you are in a child session, use: session_child_cycle (default: Right) to cycle to the next child session session_child_cycle_reverse (default: Left) to cycle to the previous child session session_parent (default: Up) to return to the parent session This lets you switch between the main conversation and specialized subagent work. Configure You can customize the built-in agents or create your own through configuration. Agents can be configured in two ways: JSON Configure agents in your opencode.json config file: opencode.json { "$schema": "https://opencode.ai/config.json", "agent": { "build": { "mode": "primary", "model": "anthropic/claude-sonnet-4-20250514", "prompt": "{file:./prompts/build.txt}", "permission": { "edit": "allow", "bash": "allow" } }, "plan": { "mode": "primary", "model": "anthropic/claude-haiku-4-20250514", "permission": { "edit": "deny", "bash": "deny" } }, "code-reviewer": { "description": "Reviews code for best practices and potential issues", "mode": "subagent", "model": "anthropic/claude-sonnet-4-20250514", "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.", "permission": { "edit": "deny" } } } } Markdown You can also define agents using markdown files. Place them in: Global: ~/.config/opencode/agents/ Per-project: .opencode/agents/ ~/.config/opencode/agents/review.md --- description: Reviews code for quality and best practices mode: subagent model: anthropic/claude-sonnet-4-20250514 temperature: 0.1 permission: edit: deny bash: deny --- You are in code review mode. Focus on: - Code quality and best practices - Potential bugs and edge cases - Performance implications - Security considerations Provide constructive feedback without making direct changes. The markdown file name becomes the agent name. For example, review.md creates a review agent. Options Let’s look at these configuration options in detail. Description Use the description option to provide a brief description of what the agent does and when to use it. opencode.json { "agent": { "review": { "description": "Reviews code for best practices and potential issues" } } } This is a required config option. Temperature Control the randomness and creativity of the LLM’s responses with the temperature config. Lower values make responses more focused and deterministic, while higher values increase creativity and variability. opencode.json { "agent": { "plan": { "temperature": 0.1 }, "creative": { "temperature": 0.8 } } } Temperature values typically range from 0.0 to 1.0: 0.0-0.2: Very focused and deterministic responses, ideal for code analysis and planning 0.3-0.5: Balanced responses with some creativity, good for general development tasks 0.6-1.0: More creative and varied responses, useful for brainstorming and exploration opencode.json { "agent": { "analyze": { "temperature": 0.1, "prompt": "{file:./prompts/analysis.txt}" }, "build": { "temperature": 0.3 }, "brainstorm": { "temperature": 0.7, "prompt": "{file:./prompts/creative.txt}" } } } If no temperature is specified, OpenCode uses model-specific defaults; typically 0 for most models, 0.55 for Qwen models. Max steps Control the maximum number of agentic iterations an agent can perform before being forced to respond with text only. This allows users who wish to control costs to set a limit on agentic actions. If this is not set, the agent will continue to iterate until the model chooses to stop or the user interrupts the session. opencode.json { "agent": { "quick-thinker": { "description": "Fast reasoning with limited iterations", "prompt": "You are a quick thinker. Solve problems with minimal steps.", "steps": 5 } } } When the limit is reached, the agent receives a special system prompt instructing it to respond with a summarization of its work and recommended remaining tasks. Caution The legacy maxSteps field is deprecated. Use steps instead. Disable Set to true to disable the agent. opencode.json { "agent": { "review": { "disable": true } } } Prompt Specify a custom system prompt file for this agent with the prompt config. The prompt file should contain instructions specific to the agent’s purpose. opencode.json { "agent": { "review": { "prompt": "{file:./prompts/code-review.txt}" } } } This path is relative to where the config file is located. So this works for both the global OpenCode config and the project specific config. Model Use the model config to override the model for this agent. Useful for using different models optimized for different tasks. For example, a faster model for planning, a more capable model for implementation. Tip If you don’t specify a model, primary agents use the model globally configured while subagents will use the model of the primary agent that invoked the subagent. opencode.json { "agent": { "plan": { "model": "anthropic/claude-haiku-4-20250514" } } } The model ID in your OpenCode config uses the format provider/model-id. For example, if you’re using OpenCode Zen, you would use opencode/gpt-5.1-codex for GPT 5.1 Codex. Tools (deprecated) tools is deprecated. Prefer the agent’s permission field for new configs, updates and more fine-grained control. Allows you to control which tools are available in this agent. You can enable or disable specific tools by setting them to true or false. In an agent’s tools config, true is equivalent to {"*": "allow"} permission and false is equivalent to {"*": "deny"} permission. opencode.json { "$schema": "https://opencode.ai/config.json", "tools": { "write": true, "bash": true }, "agent": { "plan": { "tools": { "write": false, "bash": false } } } } Note The agent-specific config overrides the global config. You can also use wildcards in legacy tools entries to control multiple tools at once. For example, to disable all tools from an MCP server: opencode.json { "$schema": "https://opencode.ai/config.json", "agent": { "readonly": { "tools": { "mymcp_*": false, "write": false, "edit": false } } } } Learn more about tools. Permissions You can configure permissions to manage what actions an agent can take. Each permission key can be set to: "ask" — Prompt for approval before running the tool "allow" — Allow all operations without approval "deny" — Disable the tool The available permission keys are: Key Tools it gates read read edit write, edit, apply_patch glob glob grep grep list list bash bash task task external_directory Any tool that reads or writes files outside the project worktree todowrite todowrite, todoread webfetch webfetch websearch websearch lsp lsp skill skill question question doom_loop Recovery prompts when an agent appears stuck read, edit, glob, grep, list, bash, task, external_directory, lsp, and skill accept either a shorthand action ("allow" | "ask" | "deny") or an object of glob/pattern → action for fine-grained control. The remaining keys accept the shorthand action only. Note Permission keys are matched as wildcard patterns against the underlying tool name, so the same syntax works for built-ins, custom tools, and MCP tools — for example "mymcp_*": "deny" denies every tool from an MCP server, and "mymcp_search": "ask" targets a single one. opencode.json { "$schema": "https://opencode.ai/config.json", "permission": { "edit": "deny" } } You can override these permissions per agent. opencode.json { "$schema": "https://opencode.ai/config.json", "permission": { "edit": "deny" }, "agent": { "build": { "permission": { "edit": "ask" } } } } You can also set permissions in Markdown agents. ~/.config/opencode/agents/review.md --- description: Code review without edits mode: subagent permission: edit: deny bash: "*": ask "git diff": allow "git log*": allow "grep *": allow webfetch: deny --- Only analyze code and suggest changes. You can set permissions for specific bash commands. opencode.json { "$schema": "https://opencode.ai/config.json", "agent": { "build": { "permission": { "bash": { "git push": "ask", "grep *": "allow" } } } } } This can take a glob pattern. opencode.json { "$schema": "https://opencode.ai/config.json", "agent": { "build": { "permission": { "bash": { "git *": "ask" } } } } } And you can also use the * wildcard to manage permissions for all commands. Since the last matching rule takes precedence, put the * wildcard first and specific rules after. opencode.json { "$schema": "https://opencode.ai/config.json", "agent": { "build": { "permission": { "bash": { "*": "ask", "git status *": "allow" } } } } } Learn more about permissions. Mode Control the agent’s mode with the mode config. The mode option is used to determine how the agent can be used. opencode.json { "agent": { "review": { "mode": "subagent" } } } The mode option can be set to primary, subagent, or all. If no mode is specified, it defaults to all. Hidden Hide a subagent from the @ autocomplete menu with hidden: true. Useful for internal subagents that should only be invoked programmatically by other agents via the Task tool. opencode.json { "agent": { "internal-helper": { "mode": "subagent", "hidden": true } } } This only affects user visibility in the autocomplete menu. Hidden agents can still be invoked by the model via the Task tool if permissions allow. Note Only applies to mode: subagent agents. Task permissions Control which subagents an agent can invoke via the Task tool with permission.task. Uses glob patterns for flexible matching. opencode.json { "agent": { "orchestrator": { "mode": "primary", "permission": { "task": { "*": "deny", "orchestrator-*": "allow", "code-reviewer": "ask" } } } } } When set to deny, the subagent is removed from the Task tool description entirely, so the model won’t attempt to invoke it. Tip Rules are evaluated in order, and the last matching rule wins. In the example above, orchestrator-planner matches both * (deny) and orchestrator-* (allow), but since orchestrator-* comes after *, the result is allow. Tip Users can always invoke any subagent directly via the @ autocomplete menu, even if the agent’s task permissions would deny it. Color Customize the agent’s visual appearance in the UI with the color option. This affects how the agent appears in the interface. Use a valid hex color (e.g., #FF5733) or theme color: primary, secondary, accent, success, warning, error, info. opencode.json { "agent": { "creative": { "color": "#ff6b6b" }, "code-reviewer": { "color": "accent" } } } Top P Control response diversity with the top_p option. Alternative to temperature for controlling randomness. opencode.json { "agent": { "brainstorm": { "top_p": 0.9 } } } Values range from 0.0 to 1.0. Lower values are more focused, higher values more diverse. Additional Any other options you specify in your agent configuration will be passed through directly to the provider as model options. This allows you to use provider-specific features and parameters. For example, with OpenAI’s reasoning models, you can control the reasoning effort: opencode.json { "agent": { "deep-thinker": { "description": "Agent that uses high reasoning effort for complex problems", "model": "openai/gpt-5", "reasoningEffort": "high", "textVerbosity": "low" } } } These additional options are model and provider-specific. Check your provider’s documentation for available parameters. Tip Run opencode models to see a list of the available models. Create agents You can create new agents using the following command: Terminal window opencode agent create This interactive command will: Ask where to save the agent; global or project-specific. Description of what the agent should do. Generate an appropriate system prompt and identifier. Let you select which permissions the agent should be allowed (anything you don’t select is denied). Finally, create a markdown file with the agent configuration. Use cases Here are some common use cases for different agents. Build agent: Full development work with all tools enabled Plan agent: Analysis and planning without making changes Review agent: Code review with read-only access plus documentation tools Debug agent: Focused on investigation with bash and read tools enabled Docs agent: Documentation writing with file operations but no system commands Examples Here are some example agents you might find useful. Tip Do you have an agent you’d like to share? Submit a PR. Documentation agent ~/.config/opencode/agents/docs-writer.md --- description: Writes and maintains project documentation mode: subagent permission: bash: deny --- You are a technical writer. Create clear, comprehensive documentation. Focus on: - Clear explanations - Proper structure - Code examples - User-friendly language Security auditor ~/.config/opencode/agents/security-auditor.md --- description: Performs security audits and identifies vulnerabilities mode: subagent permission: edit: deny --- You are a security expert. Focus on identifying potential security issues. Look for: - Input validation vulnerabilities - Authentication and authorization flaws - Data exposure risks - Dependency vulnerabilities - Configuration security issues ====================================================== Endpoints --------- Model Model ID Endpoint AI SDK Package GLM-5.1 glm-5.1 https://opencode.ai/zen/go/v1/chat/completions @ai-sdk/openai-compatible GLM-5 glm-5 https://opencode.ai/zen/go/v1/chat/completions @ai-sdk/openai-compatible Kimi K2.5 kimi-k2.5 https://opencode.ai/zen/go/v1/chat/completions @ai-sdk/openai-compatible Kimi K2.6 kimi-k2.6 https://opencode.ai/zen/go/v1/chat/completions @ai-sdk/openai-compatible DeepSeek V4 Pro deepseek-v4-pro https://opencode.ai/zen/go/v1/chat/completions @ai-sdk/openai-compatible DeepSeek V4 Flash deepseek-v4-flash https://opencode.ai/zen/go/v1/chat/completions @ai-sdk/openai-compatible MiMo-V2.5 mimo-v2.5 https://opencode.ai/zen/go/v1/chat/completions @ai-sdk/openai-compatible MiMo-V2.5-Pro mimo-v2.5-pro https://opencode.ai/zen/go/v1/chat/completions @ai-sdk/openai-compatible MiniMax M2.7 minimax-m2.7 https://opencode.ai/zen/go/v1/messages @ai-sdk/anthropic MiniMax M2.5 minimax-m2.5 https://opencode.ai/zen/go/v1/messages @ai-sdk/anthropic Qwen3.6 Plus qwen3.6-plus https://opencode.ai/zen/go/v1/chat/completions @ai-sdk/alibaba Qwen3.5 Plus qwen3.5-plus https://opencode.ai/zen/go/v1/chat/completions @ai-sdk/alibaba The model id in your OpenCode config uses the format opencode-go/. For example, for Kimi K2.6, you would use opencode-go/kimi-k2.6 in your config. ------------------------